/*
 * Created on 2005-10-9
 *
 */
package com.hd123.rumba.user;

import java.util.Date;
import java.util.Iterator;
import java.util.List;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.domain.IDomain;
import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.exception.ParameterException;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;

/**
 * 用户 | 管理员 | 接口类
 * <p>
 * 
 * <u>系统用户</u><br>
 * 为了使系统表现的向一个真正的用户一样，可以操作系统的各种功能，而提供的一个虚拟用户。<br>
 * 其事实上并不会也不应该在数据库中出现。<br>
 * 其始终属于系统根域。<br>
 * 在一般情况下，企业不应该被其它持久化实体引用。<br>
 * 调用者可以通过方法getSysUser()取得系统用户。
 * 
 * @author caili
 */
public interface IUserMgr extends IManager {

  /* logger event */
  public static final String EVENT_ASSIGNPERMISSION = "添加权限";
  public static final String EVENT_REMOVEPERMISSION = "删除权限";
  public static final String EVENT_ASSIGNROLE = "添加角色";
  public static final String EVENT_REMOVEROLE = "删除角色";

  public IUser createUser(IDomain domain, String login) throws HibernateException,
      BusinessException;

  /**
   * 创建一个用户。
   * 
   * @param domain
   *          被创建用户所属域。
   * @return 被创建的用户。
   * @throws BusinessException
   * @throws HibernateException
   */
  public IUser createUser(IDomain domain) throws BusinessException, HibernateException;

  /**
   * 根据登录名取得用户。
   * <p>
   * 只在未被删除的用户范围内搜索。
   * 
   * @param domain
   *          查找用户所属的域。
   * @param login
   *          用户的登录名。
   * @return 返回符合条件的用户，找不到则返回null。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IUser getUserByLogin(IDomain domain, String login) throws HibernateException,
      BusinessException;

  /**
   * 根据uuid取得用户。
   * 
   * @param uuid
   *          用户的uuid。
   * @return 返回符合条件的用户，若未找到则返回null。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IUser getUser(String uuid) throws HibernateException, BusinessException;

  /**
   * 根据uuid取得用户。
   * 
   * @param uuid
   *          用户的uuid。
   * @param states
   *          符合条件的用户状态取值列表，只有当用户的状态属于该集合时才会被返回。传入null，表示不约束状态条件。
   * @return 返回符合条件的用户，若未找到则返回null。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IUser getUser(String uuid, Integer[] states) throws HibernateException, BusinessException;

  /**
   * 根据uuid取得可用的用户。即状态不等于“已删除”的用户。
   * 
   * @param uuid
   *          用户的uuid。
   * @return 返回符合条件的用户，若未找到则返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public IUser getValidUser(String uuid) throws BusinessException, HibernateException;

  /** @deprecated */
  public void saveUser(IUser user) throws HibernateException, BusinessException;

  /**
   * 保存用户
   * 
   * @param user
   *          被保存的用户
   * @param operator
   * @param oca
   * @throws BusinessException
   * @throws HibernateException
   * @deprecated
   */
  public void saveUser(IUser user, IUser operator, long oca) throws BusinessException,
      HibernateException;

  /**
   * 保存用户
   * 
   * @param user
   *          被保存的用户
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveUser(IUser user, OperateContext operate) throws BusinessException,
      HibernateException;

  /**
   * 保存用户，该用户的uuid已经指定。
   * 
   * @param user
   *          被保存的用户
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveUserWithUuid(IUser user, OperateContext operate) throws BusinessException,
      HibernateException;

  /**
   * 删除指定的用户。
   * 
   * @param user
   *          被删除的用户。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void deleteUser(IUser user, OperateContext operate) throws BusinessException,
      HibernateException;

  /**
   * 恢复删除指定的用户。
   * 
   * @param user
   *          被恢复删除的用户。
   * @param operator
   * @throws BusinessException
   * @throws HibernateException
   */
  public void undeleteUser(IUser user, OperateContext operate) throws BusinessException,
      HibernateException;

  public void removeUser(IUser user) throws HibernateException, BusinessException;

  public List createAllUsersList(IDomain domain) throws HibernateException, BusinessException;

  /** @deprecated */
  public void assignPermissionToUser(IPermission perm, IUser user) throws HibernateException,
      BusinessException;

  /**
   * 赋权限到指定用户。
   * 
   * @param perm
   *          指定的权限
   * @param user
   *          被赋权的用户
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void assignPermissionToUser(IPermission perm, IUser user, OperateContext operate)
      throws HibernateException, BusinessException;

  public boolean hasPermission(IUser user, IPermission perm) throws HibernateException,
      BusinessException;

  /** @deprecated */
  public void removePermissionFromUser(IPermission perm, IUser user) throws HibernateException,
      BusinessException;

  /**
   * 从指定的用户中删除已有权限。
   * 
   * @param perm
   *          指定的权限
   * @param user
   *          指定的用户
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void removePermissionFromUser(IPermission perm, IUser user, OperateContext operate)
      throws HibernateException, BusinessException;

  /**
   * 返回user固有的权限列表. 直接的权限, 不包括通过角色得到的权限.
   * 
   * @param user
   * @return List of IPermission
   * @throws HibernateException
   * @throws ParameterException
   */
  public List createPermissionsList(IUser user) throws HibernateException, BusinessException;

  /** @deprecated */
  public void assignRoleToUser(IRole role, IUser user) throws HibernateException, BusinessException;

  /**
   * 向指定用户添加角色
   * 
   * @param role
   *          指定添加的角色
   * @param user
   *          指定的用户
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void assignRoleToUser(IRole role, IUser user, OperateContext operate)
      throws HibernateException, BusinessException;

  /**
   * 返回指定用户是否拥有指定的角色。<br>
   * 只有当角色可用的时候，才可能返回true。
   * 
   * @param user
   *          指定的用户。
   * @param role
   *          指定的角色。
   * @return 返回是否拥有角色。
   * @throws HibernateException
   * @throws BusinessException
   */
  public boolean hasRole(IUser user, IRole role) throws HibernateException, BusinessException;

  /** @deprecated */
  public void removeRoleFromUser(IRole role, IUser user) throws HibernateException,
      BusinessException;

  /**
   * 从指定的用户中删除角色
   * 
   * @param role
   *          被删除的角色
   * @param user
   *          指定的用户
   * @throws HibernateException
   * @throws BusinessException
   */
  public void removeRoleFromUser(IRole role, IUser user, OperateContext operate)
      throws HibernateException, BusinessException;

  /**
   * 取得指定用户所拥有的角色列表。<br>
   * 只返回可用的角色列表。
   * 
   * @param user
   *          指定的用户。
   * @return List of IRole 返回角色列表。
   * @throws HibernateException
   * @throws ParameterException
   */
  public List createRolesList(IUser user) throws HibernateException, BusinessException;

  /**
   * 取得user通过授权得到的PermissionCommission
   * 
   * @param user
   * @return List of IPermissionCommission
   * @throws HibernateException
   */
  public List createCommissionedPermissionsList(IUser user) throws HibernateException,
      BusinessException;

  /**
   * 取得fromUser授权给toUser的权限授权列表
   * 
   * @param fromUser
   * @param toUser
   * @return List of IPermissionCommission
   * @throws HibernateException
   */
  public List createCommissionedPermissionsList(IUser fromUser, IUser toUser)
      throws HibernateException, BusinessException;

  /**
   * 取得user授出的PermissionCommission
   * 
   * @param user
   * @return List of IPermissionCommission
   * @throws HibernateException
   */
  public List createCommissionPermissionsList(IUser user) throws HibernateException,
      BusinessException;

  /**
   * 授权. fromUser必须具有分配的(不是授权得到的)权限perm. 所有的参数都是必须的.
   * 
   * @param fromUser
   * @param toUser
   * @param validFrom
   * @param validTo
   * @param perm
   * @return boolean 表示成功或失败.
   * @throws ParameterException
   * @throws HibernateException
   */
  public boolean grantPermission(IUser fromUser, IUser toUser, Date validFrom, Date validTo,
      IPermission perm) throws BusinessException, HibernateException;

  public void revokePermission(IUser fromUser, IUser toUser, IPermission perm)
      throws BusinessException, HibernateException;

  /**
   * 返回具有给定权限的用户集. 这里的权限是固有权限, 不包括授权的权限.
   * 
   * @param permissionId
   * @return Iterator of IUser
   */
  public Iterator createUsersHavingPermissionIdIterator(String permissionCode)
      throws HibernateException, BusinessException;

  /** @deprecated 被{@link #login(String, String, String, String)}替代。 */
  public LoginResult login(String login, String password, String domainCode)
      throws BusinessException;

  /**
   * 登录验证。
   * 
   * @param login
   *          登录名
   * @param password
   *          密码
   * @param tokenValue
   *          令牌值
   * @param domainCode
   *          登录域代码
   * @return 登录结果。如果登录成功，则返回结果中包含用户、组织等信息，如果登录失败，则可以从返回结果中getErrorText取出错误信息。
   * 
   * @throws BusinessException
   */
  public LoginResult login(String login, String password, String tokenValue, String domainCode)
      throws BusinessException;

  public void logout(IUser user) throws BusinessException;

  /**
   * 取得系统用户。
   * 
   * @return
   * @throws BusinessException
   */
  public IUser getSysUser() throws BusinessException;
}
